Indicator that user clicked or double-clicked in a list box.
The doListBox event reports that the user has clicked somewhere in a list box (on a line that contains text or a blank line). This event is not generated when the user just scrolls the list box by using its scroll bar.
Programming Considerations
``````````````````````````
• If your application treats double-clicks in list boxes like clicking
the OK button, use the GetListBoxLine function to determine which line
was selected (or GetListBoxLines if multiple lines can be selected in
the list box), then flash the OK button with the FlashButton
procedure.
• This event will never occur when the watch cursor is displayed, since
list boxes cannot be clicked.
• A doListBox event is not generated when the user clicks list boxes in
a dialog box or desk accessory. These events are handled
Indicator that the user has completed or in the midst of a click, double-click, triple-click, or drag.
A click, double-click, triple-click, or drag has been reported in the active window. The event may still be in progress when PollSystem reports it, such as a double-click with the mouse button still down on the second click. The Mouse part of the event record contains a field called What, which is the mouse event code that tells your application what type of mouse click has occurred. The rest of the mouse record contains details on each mouse-down and mouse-up event.
A series of decisions are made by PollSystem to obtain single and multiple-click information, as well as drags. Although they can be somewhat altered by your application (as explained later), the steps taken are as follows:
1 The first mouse-down of a click is in the active window’s content
region, and is not in a button, picture button, scroll bar, editing
field, list box, pop-up menu or custom control.
2 If no mouse-up event is in the queue, a “single-click, mouse still
down” mouse event code is returned. If a mouse-up event is in the
queue, it is used to complete the click.
3 If the time between the first mouse-down and the first mouse-up
(single-click) is too long to be the first click of a multiple
click, PollSystem returns with a “single-click completed” mouse
event code.
4 If the time between the first mouse-down and the first mouse-up
(single-click) is short enough to constitute the first click of a
multiple click, PollSystem checks the event queue for a mouse-down
event that would be the beginning of a second click. If a mouse-
down event is not found in time, PollSystem returns with a “single-
click completed” mouse event code.
5 If a second mouse-down event is in the queue, it must be in the
active window’s content region, and must not be in a button, picture
button, scroll bar, editing field, list box, pop-up menu or custom
control. If any of these conditions are violated, the mouse-down
event is left in the queue and PollSystem returns with a “single-
click completed” mouse event code. If the conditions are not
violated, PollSystem continues.
6 The second click has begun. If no mouse-up event is in the queue, a
“double-click, mouse still down” mouse event code is returned. If a
mouse-up event is in the queue, it is used to complete the click.
7 If the time between the second mouse-down and the second mouse-up
(double-click) was too long to be the second click of a triple-
click, PollSystem returns with a “double-click completed” mouse
event code.
8 If the time between the second mouse-down and the second mouse-up
(double-click) is short enough to constitute the second click of a
triple-click, PollSystem checks the event queue for a mouse-down
event that would be the beginning of a third click. If a mouse-down
event is not found in time, PollSystem returns with a “double-click
completed” mouse event code.
9 If a third mouse-down event is in the queue, it must be in the
active window’s content region, and must not be in a button, picture
button, scroll bar, editing field, list box, pop-up menu or custom
control. If any of these conditions are violated, the mouse-down
event is left in the queue and PollSystem returns with a “double-
click completed” mouse event code. If the conditions are not
violated, PollSystem continues.
10 The third click has begun. If no mouse-up event is in the queue, a
“triple-click, mouse still down” mouse event code is returned. If a
mouse-up event is in the queue, it is used to complete the click and
return a “triple-click completed” mouse event code.
Programming Considerations
``````````````````````````
• If at some point your application is only concerned with a mouse down
in a certain area, or a single-click only, or a double-click only, you
can disrupt the click as soon as you have obtained enough information
by using ResetMouseClicks. For example, if your application only
cares about a single-click and it gets a “double-click, mouse still
down” mouse event code, ResetMouseClicks will tell PollSystem “forget
the rest of this click.”
• A triple-click should be scrutinized by your application because the
time between the third mouse-down and the third mouse-up may be longer
than the allowable limit for consecutive clicks. This will also
happen when the user double-clicks, then presses down the mouse button
the third time and drags. Use the GetDblTime function to determine
the maximum number of clock ticks which can occur between mouse-down
and up events to constitute a consecutive click.
• Your application can place cursor zones on a window, then use
FindCursorZone to determine if a click occurred in one of those zones.
This can make parts of your window, such as pictures or icons, click-
sensitive. See “Cursors” for information about Cursor Tables and
Cursor Zones.
• This event will never occur when the watch cursor is displayed, since
only buttons can be (optionally) clicked.
• Poll.Event is populated with the mouse-down event (as obtained from
the toolbox Event Manager) that is responsible for the doClick event.
Some applications need this event to drive custom controls.
• A doClick event is not generated when the user clicks in a desk
accessory’s editing fields. The process is handled automatically.
Valid Polling Record Fields
```````````````````````````
Poll.Window
Poll.Mouse.What
Poll.Mouse.Down[1].Where
Poll.Mouse.Down[1].When
Poll.Mouse.Down[1].Modifiers
Poll.Event (for first mouse-down event only)
The next three fields are valid only if the mouse event code is inClick1, inClick2Drag, inClick2, inClick3Drag, or inClick3.
Poll.Mouse.Up[1].Where
Poll.Mouse.Up[1].When
Poll.Mouse.Up[1].Modifiers
The next three fields are valid only if the mouse event code is inClick2Drag, inClick2, inClick3Drag, or inClick3.
Poll.Mouse.Down[2].Where
Poll.Mouse.Down[2].When
Poll.Mouse.Down[2].Modifiers
The next three fields are valid only if the mouse event code is inClick2, inClick3Drag, or inClick3.
Poll.Mouse.Up[2].Where
Poll.Mouse.Up[2].When
Poll.Mouse.Up[2].Modifiers
The next three fields are valid only if the mouse event code is inClick3Drag, or inClick3.
Poll.Mouse.Down[3].Where
Poll.Mouse.Down[3].When
Poll.Mouse.Down[3].Modifiers
The next three fields are valid only if the mouse event code is inClick3.
Poll.Mouse.Up[3].Where
Poll.Mouse.Up[3].When
Poll.Mouse.Up[3].Modifiers
Poll.Mouse.Where
CONST {Mouse Event Codes }
inClick1 = 1; {single-click completed }
inClick2 = 2; {double-click completed }
inClick3 = 3; {triple-click completed }
inClick1Drag=-1; {single-click, mouse still down }
inClick2Drag=-2; {double-click, mouse still down }
inClick3Drag=-3; {tripple-click, mouse still down }
Note: For C programmers… The polling record’s arrays are documented is
using Pascal nomenclature (the elements are numbered 1, 2 and 3).
In C, the same array’s elements are numbered 0, 1 and 2 (they
start at zero). When C programmers read:
Poll.Mouse.Down[1].Where
it indicates the first element of the array, which translates to
Indicator that user has clicked a picture button, or is holding down a repeating picture button.
The doPictButton event reports that the user has clicked a picture button in the active window. The doPictButton event is also reported if the user holds down a repeating picture button. Repeating picture button’s will produce events as long as: [1] the mouse button is held down, [2] the button does not reach the end of its range, and [3] the mouse pointer stays inside the picture button’s region.
Programming Considerations
``````````````````````````
• If the “automatic value change” option is not on, your application has
to set the picture button’s value by using SetPictButtonVal or
SetPictButtonValSelect.
• If you have created a picture button that is “lock selected” with the
“automatic value change” option off, and you’ve done this to validate
the picture button before proceeding to the next stage, do the
following: validate the button. If it can proceed to the next stage,
use SetPictButtonValSelect to deselect the button and increment its
value, otherwise use SetPictButtonValSelect to deselect the button and
leave its value unchanged.
• If the user clicked a picture button that is functioning like a radio
button, use SelectPictButton to deselect the other picture buttons in
the group.
• This event will never occur when the watch cursor is displayed, since
picture buttons cannot be clicked. The exception is if the
WatchCursorButtons procedure has been used to allow the watch cursor
to click picture buttons.
• Picture buttons with the “repeating events” option turned on may
produce doNothing events if your application calls PollSystem more
frequently than the button changes its value. This will cause no ill
side-effects, but you should be aware of this.
• A doPictButton event is not generated when the user clicks picture
buttons in another application, control panel or desk accessory.
These events are handled automatically.
• A negative button number value indicates that the decrementing half of
a split button was clicked (i.e., “-5” indicates that button 5 is a
The doClickControl event reports that the user has clicked in a custom control. This event must be handled entirely by your application, since only you know how your custom control should behave.
Programming Considerations
``````````````````````````
• This event will never occur when the watch cursor is displayed, since
Indicator that an event has been reported that can’t be processed by Tools Plus.
The doManualEvent event reports that some type of event has occurred which should be processed by your application. This includes seven (7) possible types of events as defined by the Toolbox Event Manager, which are listed below. If your application does not make use of any of these events, it can ignore the doManualEvent event code.
diskEvt The Standard File Package takes care of all disk-inserted
events, so applications using this package can ignore
diskEvt events. If your application is unusual and it
circumvents the Standard File package, your application
will have to handle disk-inserted events itself.
networkEvt Your application needs to respond to network events only
if it is going to be communicating with the AppleTalk
manager. If it is, you should read the appropriate
documentation in chapter 10 Vol. 2 of Inside Macintosh
regarding networks.
driverEvt If your application does not intend to work with device
drivers, it can ignore these events. Otherwise, you
should read the appropriate documentation in Inside
Macintosh regarding device drivers.
app1Evt Application-defined events 1 through 4. These are events
app2Evt whose meaning is defined by your application. If your
app3Evt application does not define custom events, it can ignore
app4Evt these event codes. Note that app4Evt (or osEvt) will
osEvt only be reported if your application does not respond to
Suspend/Resume events. See the SIZE resource for
details. If your application does respond to Suspend/
Resume events, it will receive a doSuspend or doResume
Tools Plus event.
kHighLevel- Your application needs to respond to these events only if
Evt you have defined the SIZE resource to respond to high-
The doMoveWindow event reports that the user has repositioned a window by dragging it by its title bar. Most applications will choose to ignore this event.
Programming Considerations
``````````````````````````
• The dragged window might not be the active window. The user can drag
an inactive window by holding down the Command key before beginning
the drag.
• If part or all of a window is exposed by the drag and needs to be
refreshed, a subsequent call to PollSystem will report a doRefresh
event for this window.
• Your application may call WindowStatus to obtain the window’s new
location in the screen’s global co-ordinates.
• This event will never occur when the watch cursor is displayed, since
the title bar cannot be clicked.
• A doMoveWindow event is not generated when the user drags a desk
The doClickDesk event reports that the user has clicked in the desk top. Most applications will choose to ignore this event, however, it can be used to deselect objects on the active window.
Programming Considerations
``````````````````````````
• This event will never occur when a modal window is active, since
clicks cannot occur outside of the window.
• This event will never occur when the watch cursor is displayed, since
Indicator that user has changed a window’s size and/or location by zooming.
The doZoomWindow event reports that the user has changed a window’s size and/or position by clicking the “zoom box.” This will always occur on the active window. Applications will typically ignore this event, or treat it similarly to the doGrowWindow event.
Programming Considerations
``````````````````````````
• Your application can call the WindowStatus procedure to obtain the
window’s new width and height in pixels, as well as its new location
in the screen’s global co-ordinates.
• The window’s entire contents are erased during the zoom. A subsequent
call to PollSystem will report a doRefresh event for this window.
Responding to the doRefresh event will regenerate the window’s
contents.
• This event will never occur when the watch cursor is displayed, since
the zoom box cannot be clicked.
• A doZoomWindow event is not generated when the user click’s a desk
accessory’s zoom box. The process is handled automatically.
Indicator that your application is about to be suspended.
The doSuspend event reports that your application will be suspended (or become a “background” application) the next time you call PollSystem. This occurs under MultiFinder or System 7 when a desk accessory or other application is launched, or when an inactive window belonging to a desk accessory or another application is activated.
Programming Considerations
``````````````````````````
• If your application is cutting, copying or pasting specialized objects
(i.e. not text that is handled by editing fields), copy this material
The doResume event reports that your application has become the active application. This occurs under MultiFinder or System 7 after your application has become suspended (see the doSuspend event).
Programming Considerations
``````````````````````````
• If your application is cutting, copying or pasting specialized objects
(i.e. not text that is handled by text editing fields), you may want
to check the clipboard to see if it contains the specialized objects
that you can paste, then copy them to your local scrap.
Indicator that the contents of your application’s active editing field have been changed.
The doChgInField event is reported whenever the active field in your application is altered, either through typing, cutting, pasting (including the use of the PasteIntoField routine), clearing, or undoing/redoing (using the Edit menu). Most applications will ignore this event.
Set the number of ticks (1/60 sec) your application can wait until it receives a doNothing event, and can perform one cycle of its background process. These settings affect only doNothing events.
pascal void SetNullTime (long ForegroundTime; long BackgroundTime);
ForegroundTime is the amount of time (in 1/60 second “ticks”) your application can wait between receiving doNothing events when the application is the active application. You can specify a value from 0 (maximum background processing speed at the expense of other applications) to 15 (four cycles per second).
BackgroundTime is the amount of time (in 1/60 second “ticks”) your application can wait between receiving doNothing events when the application is suspended (i.e. when another application is active under MultiFinder or System 7).
By default, Tools Plus is initialized with ForegroundTime and BackgroundTime set to 0, meaning your application will have maximum performance at the expense of other applications and processes. Normally, applications that do background processing will set ForegroundTime to 1, and BackgroundTime to a higher value, thus slowing down the background processing when your application is suspended. If your application doesn’t do any background processing, use the maxNullTime constant to allow other applications and process the maximum utilization of the processor.
Your application can change the values of ForegroundTime and BackgroundTime at any time. The change will take effect the next time that PollSystem is called.
Also see: WaitAvail.
CONST {Background process scheduling }
maxNullTime = $7FFFFFFF; {Infinite time between doNothing events }
Determine if the Macintosh running your application supports scheduled processing. This determines if SetNullTime’s settings will have any effect.
pascal Boolean WaitAvail(void);
function WaitAvail: BOOLEAN;
This function returns a value of true if scheduled background processing is supported, or false if it is not. If the Macintosh running your application doesn’t support scheduled background processing, then SetNullTime’s settings will have no effect, and your application will receive a doNothing event each time it calls PollSystem when there are no events available. Internally, this routine reports if the WaitNextEvent trap is available to your application.
Discontinue a mouse’s “drag” or multiple clicks in progress.
pascal void ResetMouseClicks(void);
procedure ResetMouseClicks;
The PollSystem function is used to detect single-clicks, double-clicks, and triple-clicks, as well as dragging which occurs between a mouse-down and mouse-up event. In some applications, it may suffice to know that the user pressed the mouse button with the cursor being within a specific region or cursor zone, without concern for the mouse button’s release. Or an application may allow a single-click only, thereby disallowing double or triple clicks.
In such cases, the ResetMouseClicks procedure can be used to tell Tools Plus that sufficient mouse information has been retrieved, and to reset the click and drag mechanism. This reset will clear the current click or drag from PollSystem’s event queue. The next time the mouse button in pressed down, it will be considered to be a first mouse-down of either a single-click, double-click, triple-click, or drag.
See PollSystem for details on how the system responds to mouse events.
Determine if your application has been suspended (i.e. not the active application).
pascal Boolean ApplicationSuspended(void);
function ApplicationSuspended: BOOLEAN;
This function returns a value of true if a desk accessory or another application is active under MultiFinder or System 7). A value of false is returned if your application is active, even though your application may not have any windows open.
When running under MultiFinder or System 7, your application needs to have a SIZE resource with the “AcceptSuspendEvents” bit set to “1.” See the SIZE resource for details.
